package com.southminority.ethnic.service.research;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.pojo.Paper;
import com.southminority.ethnic.controller.research.vo.PaperVO;

import java.util.List;

/**
 * 学术论文服务接口.
 * <p>
 * 定义了学术论文模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 *
 * @author SouthMinority
 */
public interface PaperService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================
    
    /**
     * 分页查询已发布的学术论文列表（用于前端列表页）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param keyword       搜索关键词 (可选, 模糊匹配标题、作者、关键词).
     * @param paperType     论文类型 (可选, 精确匹配).
     * @param year          发表年份 (可选, 精确匹配).
     * @return {@link PageResult<PaperVO>} 封装了分页信息的查询结果.
     */
    PageResult<PaperVO> getPublishedPaperPage(Integer page, Integer size, String keyword, String paperType, Integer year);

    /**
     * 获取单个已发布论文的详细信息（用于前端详情页）.
     *
     * @param id 论文的唯一标识ID.
     * @return {@link PaperVO} 包含完整信息的论文视图对象.
     */
    PaperVO getPaperDetail(Long id);
    
    /**
     * 增加指定论文的下载次数.
     *
     * @param id 论文ID.
     */
    void increaseDownloadCount(Long id);

    /**
     * 获取所有不重复的论文发表年份列表（用于前端筛选菜单）.
     *
     * @return {@link List<Integer>} 年份列表.
     */
    List<Integer> getPaperYears();
    
    /**
     * 获取所有不重复的论文类型列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 论文类型字符串列表.
     */
    List<String> getPaperTypes();

    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================
    
    /**
     * 分页查询所有学术论文信息（用于后台管理列表）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param keyword       搜索关键词 (可选, 模糊匹配标题、作者).
     * @param paperType     论文类型 (可选, 精确匹配).
     * @param status        状态 (可选, 1-已发布, 0-草稿).
     * @return {@link PageResult<PaperVO>} 封装了分页信息的查询结果.
     */
    PageResult<PaperVO> getPaperPageForAdmin(Integer page, Integer size, String keyword, String paperType, Integer status);

    /**
     * 根据ID获取论文详情（用于后台管理编辑页）.
     *
     * @param id 论文的唯一标识ID.
     * @return {@link PaperVO} 包含完整信息的论文视图对象.
     */
    PaperVO getPaperDetailForAdmin(Long id);

    /**
     * 创建一篇新的学术论文.
     *
     * @param paper 包含论文所有信息的POJO对象.
     * @return {@link PaperVO} 创建成功后返回的论文视图对象.
     */
    PaperVO createPaper(Paper paper);
    
    /**
     * 更新一篇已存在的学术论文.
     *
     * @param id    要更新的论文的ID.
     * @param paper 包含更新后信息的POJO对象.
     * @return {@link PaperVO} 更新成功后返回的论文视图对象.
     */
    PaperVO updatePaper(Long id, Paper paper);
    
    /**
     * 根据ID删除一篇学术论文（逻辑删除）.
     *
     * @param id 要删除的论文的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean deletePaper(Long id);
    
    /**
     * 批量删除学术论文（逻辑删除）.
     *
     * @param ids 包含多个要删除的论文ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean batchDeletePapers(List<Long> ids);
    
    /**
     * 更新指定论文的状态.
     *
     * @param id     论文的ID.
     * @param status 新的状态值 (例如: 1-已发布, 0-草稿).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean updatePaperStatus(Long id, Integer status);
} 
